SIX12

			Debugging  Control  Module
			--------------------------


					R. K. Johnsson
					C. B. Weinstock
					Wm. A. Wulf
					T. Lane
					R. F. Brender
					J. M. Newcomer
					August 31, 1979


->	This module contains a driver to allow interactive
	debugging of a Bliss/10 or Bliss/36 program.  Essentially the 
	service provided by this module is:

	   1.	Monitor the TTY to allow the user to interrupt
		his program and enter the debug module.  If, during
		execution, any character is typed on the TTY (except
		during input wait) SIX12 will shortly intercept control and
		wait for the user to complete the debug command.
	   2.	Provide syntax analysis and evaluation of expressions
		input to the debugger.  The user defines his own
		operations by means of Bliss routines.  A set of
		generally useful operations is included in this
		package;  the intention, however, is that the user
		may write his own routines which are specific
		to the problem, and use this package merely as a
		standard interface.

	This file is intended only as a compact (i.e., incomplete)
	at-terminal reference.  See SIX12.DOC for a complete manual.

The SIX12 files are:
	SIXA12.REL[N110SX12]		Bliss-10 linkages
	SIXB12.REL[N110SX12]		Bliss-36 linkages

->	The set of standard operators is:


    =  .  +  -  *  /  ↑  @	all have exactly their Bliss
    ( )  < >  NOT  AND  OR	interpretation, except that <>
    GEQ through LSS		accept only position and size,
				and = does not have a value.
		A[S]		Structure access. The 
				structure is the default VECTOR,
				so this is equivalent to (A+S)<0,36>.
				With three or four parameters, the BLOCK
				structure is used.  If SIXREF is set
				to a true value, a REF-structure access
				is done.
		R(P1,,,Pn)	Call the routine named R with
				parameters P1,,,Pn.
		P1/		Print the contents of location P1.
		P1!P2		Print P2 locations beginning at P1.
		BREAK P1,...,Pn Set break points at the heads of
				routines P1,...,Pn.
		DBREAK P1,,,Pn	Remove break points set as above.
		ABREAK P1,,,Pn	Set break points at the exit of routines
				P1,,,Pn.
		DABREAK P1,,,Pn	Remove abreak points set as above.
		CALLS		Display the stack of routine calls.
		LCALLS		Display call stack and locals --
				the latter may not be very useful
				unless the user is very familiar
				with the Bliss run-time environment.
		CALL n		Print the last n calls on stack.
				If n is omitted, print last call.
		LCALL n		Same as above but also displays locals.
		BASE n		Sets the default number base to n
				(1<n<11).  Subsequent input numbers
				are assumed to be in this base
				(except when prefixed by #), and output
				numbers will be printed in this base.
				# immediately preceding a number means octal
				input except when the default base is
				octal, in which case # means decimal.
				If n is omitted BASE prints the current
				default base in decimal.
		WBASE n		Sets the maximum size of displacement
				that will be printed in 'base+displacement'
				output to n. (W is for Wulf for historical
				reasons.)  Initially set 1000(octal).
				If n is omitted, the current limit is
				printed (in the current default base).
		DDT		Call DDT (in CMU-DDT an $P to DDT
				will cause resumption in SIX12).
		GO		Resume executing user program.
		SETTRACE	Turns on trace mode. Will display
				call stack for routines as they
				are entered and left.
		GOTRACE		Equivalent to SETTRACE;GO. Execution
				is resumed in trace mode.
		CLRTRACE	Turns off trace mode.
		RETURN exp	The action of this function depends
				on how SIX12 has been entered.
				If you have stopped at a routine
				exit (ABREAK), this is the same
				as GO except that exp is the value returned
				for the routine being left. If you have
				stopped at a routine entry (BREAK), execution
				of the routine is suppressed completely,
				and control returns to the caller with
				the value exp. If you have made an explicit call
				to SIX12 (see use note #3), control
				returns following the call, with the value exp.
				(If an explicit call is terminated by
				GO or GOTRACE, it returns -1.)
		DISABLE		Turns off typein monitoring, allows type-ahead.
				To resume typein monitoring enter
				DDT and set ENABFLG in SIX1.. to 1.
				Monitoring is automatically
				re-enabled at any break point.
		NODEBUG		This performs
				JOB41 ← #255000000000		(JFCL 0)
				GO
				Thus, the DEBUG UUO is rendered a
				no-op.  This can be used to improve execution
				speed when you don't intend to use SIX12.
		PRS P1,,,Pn	Prints a list of all DDT symbol table
				entries for P1,,,Pn. A * next to an entry
				means that that entry will not be used for
				typeout by DDT or SIX12.
		SEARCH 'name'	This is an alternative to PRS, which allows
				searches using the PIP question-mark convention.
				The name must be entered in single quotes.
				Example:
				& SEARCH  'P??'
				PRG	...
				PR	...
		OPAQUE P1,,,Pn	Makes the named routines opaque to tracing,
				i.e., if the routine is entered with tracing turned
				on, tracing is turned off until the matching routine
				exit is encountered.
		OPAQUE AFTER P1,,,Pn	Works as OPAQUE except that the
				routine itself is traced.  If this action
				is set for a routine X, the trace printout
				for X is only one line, not two:
				--> X from caller 
					Actuals: parms    Value: value
		TRACE P1,,,Pn	Entry and exit of the named routines
				are traced, unless OPAQUE is in
				effect. Trace information is never
				printed inside an OPAQUEd routine.
		TRACE AFTER P1,,,Pn	Unless OPAQUE is on, tracing occurs
				inside the named routines, i.e. every
				routine they call directly or indirectly
				is traced.
		TRACE FROM P1,,,Pn	Equivalent to TRACE plus TRACE AFTER.
		DOPAQUE P1,,,Pn		Cancel the corresponding function.
		DOPAQUE AFTER P1,,,Pn
		DTRACE P1,,,Pn
		DTRACE AFTER P1,,,Pn
		DTRACE FROM P1,,,Pn
		MONITOR P1,,,Pn	Monitors the locations P1,,,Pn. If
				value changes, tells where and how, and breaks.
				P1,,,Pn may be byte specifications, e.g.
				MONITOR FLAG<1,1>,FLAG<17,1>,CHAR,CHANNEL<18,18>
		DMONITOR P1,,Pn	Turns off monitoring.
		STEP		Execute until the next SIX12 event, then
				break.  <linefeed> is equivalent to STEP.
		OK		If at routine entry, set a temporary ABREAK
				at the routine exit and GO.  Upon hitting
				the temporary ABREAK, remove it and break.
->		LPTOPEN		Opens a file SIX12.LPT on logical
				device LPT.  This file is used
				for output from SIX12 when the output switch
				is so set. The file facility is
				intended to make large amounts of
				trace output, etc. easier to deal with.
				Warning: This facility uses logical channel
				#17.  Do not use it if your program does
				I/O on channel #17.
		LPTCLOSE	Closes the file opened by
				LPTOPEN.  All file output between
				one pair of OPEN and CLOSE is a
				logical unit.
		LPTON		Subsequent output from SIX12
				(except error messages)
				will be directed to the file.
		LPTOFF		Output is sent to the TTY.  Note that the
				file is not closed, so if more
				file output is done later it
				will be written in the same file.
				Every break to SIX12 causes an automatic LPTOFF.
		LPTDUP		Output is written to both.
		DEFINE op,parse=prio,routn	"Op" is written
				either as "char" for a special
				character or as  name
				for a symbol. Parse is one of
					NULL	or 0
					PREFIX	or 1
					POSTFIX	or 2
					INFIX	or 3
				Prio and routn are the new data for the
				specified parse (see SIX12.DOC).
				For example,
				DEFINE LOOK,PREFIX= 20,XLOOKAT
				DEFINE "↑",3= 25,SHIFTIT
		MACRO name=|text|	This defines a
				SIX12 macro named 'name'. SIX12 supports
				no-argument, simple text substitution
				macros only. The macro can be called
				simply by giving its name, e.g.
				&MACRO AB=|ABREAK|
				&AB R1,R2,KKK
				&MACRO DEMO=|1,2,3,.PTEXT|
				&DEMO
					1	1
					2	2
					3	3
				    63433	TEXTAR+11
		FORGET N1,,,Nn	Deletes macros.
->		SAVE 'filespec'	This operator saves all currently defined
				macros, the MONITORs table, and the table of
				routine actions (i.e., BREAKs, TRACEs, etc.)
				on the disk file specified by filespec (which
				should be enclosed in single quotes).
		LOAD 'filespec'	This operator deletes all existing macros,
				the MONITORs table, and the table of routine
				actions, then loads the macros and tables
				found in the SAVE-written disk file
				specified by filespec.
				Warning: SAVE and LOAD use I/O channel #16.
				Do not use them while your program has
				anything open on #16.
				Note: Since the monitor and actions tables
				contain absolute memory addresses, SAVE/LOAD
				should not be used to preserve actions
				or MONITORs through a program link.
				Use STORE/RECALL instead.
				Note: The proper way to recover from the
				'No space for macro text' error is to delete
				any unneeded macros and actions, then
				SAVE 'TEMP';LOAD 'TEMP'
		STORE 'filespec'	Stores all BREAKs, TRACEs,
				OPAQUEs, etc. as well as MACROs,
				MONITORs and BINDs as a text file.
				This text file, or any other text file
				containing SIX12 commands, may be loaded
				with the RECALL command.
		RECALL 'filespec'	Loads a text file (line numbers
				are permitted) containing SIX12 commands.
				Like SAVE/LOAD, STORE/RECALL use channel #16.
		BIND sym=exp	'sym' is entered in the DDT symbol table
				with value exp, e.g.
				BIND X1 = X+1
				Note: BIND is the best way to create named
				debugging temporaries. For example,
					BIND MYNAME= SIXPAT[2]
				or	BIND PI4 = (.JOBFF)<0,36>; JOBFF←.JOBFF +1
		PRINT		Prints state information about SIX12.
				PRINT OPER "char"
				PRINT OPER name
				prints the definition of that operator
				(priority and routine name for each parse).
				PRINT MACRO name
				prints the text of macro 'name'.
				PRINT ACTION action routine
				prints the status of the specified action,
				which should be given as:
				BREAK  ABREAK  OPAQ  OPAQAFT  TRACE  or  TRACEAFT
				The possible responses are
				'Action not set'
				'Unconditional'
				or text of condition test (see below). E.g.,
				& PRINT ACTION OPAQ XYZ
				Action not set
				& PRINT ACTION ABREAK PPPP
				.X LSS 3
				PRINT MONITOR
				Prints all of the monitored locations and
				their last recorded value.
->		Conditional functions:
			The routine functions listed above (BREAK, ABREAK,
			any of the varieties of TRACE and OPAQUE) can
			be made conditional by giving a text to be
			evaluated.  The format is
		IF |test| BREAK P1,,,Pn			
			(or ABREAK, OPAQUE, TRACE, etc.). 'Test'
			must be a SIX12 expression yielding 1 or 0 in
			the low-order bit according to whether the action
			should be taken, e.g.
		IF |.COUNT LSS 3| TRACE FROM XERROR
			This condition will be re-evaluated each time
			XERROR is entered (unless tracing is already on
			or an OPAQUE is in effect).  IF is a noise word
			and can be dropped:
		|.COUNT LSS 3| TRACE FROM XERROR
			Issuing either Daction or an unconditional
			action removes the condition;
			the same function on a single routine
			cannot have both conditional and unconditional
			definitions.  (Note: conditions set on routine
			exits may find it necessary to test the value
			which was returned.  The value is available in
			the global SIXVREG in SIX12.)  SAVE and LOAD will
			save and restore these conditions.


->	Note:
	    In order to use this package the modules to be
	debugged must be compiled with the proper compilation
	control, namely:

	    1.	"TIMER=EXTERNAL(SIX12)" must appear in the main
		module head.  (At present timing and debugging
		should not be attempted at once.)
	    2.	Either "/D" must be used in each command string,
		or "DEBUG" must appear in each module head.
	    3.	Don't use DEC Bliss - it doesn't generate all the necessary
		linkages. Use CMU Bliss only.


->	Use notes:

	    1.  Because it is sometimes useful to enter this package 
		immediately upon the start of execution (after stack
		initialization), a facility to do this has
		been provided.  Enter DDT and type:
			SIX1..$:	STARTFLG!	1 <CR>
			$G  
		If your program does not use the name STARTFLG, then
		the SIX1..$: can be eliminated. (Note: $ is altmode)

	    2.	To reduce symbol table size (and the possibility
		of confusion), SIX12 can be loaded without its local
		symbols. (All global symbols in SIX12 begin with the
		letters S I X).  The only non-global symbols you
		are likely to need in SIX12 are STARTFLG and ENABFLG;
		they can be accessed as SIX1.O and SIX1.O+1, respectively.
	    3.	SIX12 may be called directly by the program to
		cause a program stop. Call SIX12 with any
		parameter* to do this, e.g.
			EXTERNAL SIX12;
			.
			.
			SIX12(10);
		SIX12 prints the parameter value and the stop location:
			PAUSE n AT location
		A 'GO' command to SIX12 resumes execution following
		the call.

	    4.	The debugging linkages generated by Bliss (under the /D switch)
		use the #037 user UUO.  If your program makes no use of
		user UUOs (opcodes #001-#037), you don't need to worry
		about this fact; SIX12 initializes location #41 automatically.
		Otherwise, you must see to it that your UUO handler will link
		to SIX12 properly.  Since SIX12's UUO handler is not global,
		the initialization code in your main module must get the
		proper jump address from #41 (already loaded by this point):
			UUOHANDLERS[#037] ← .JOB41<0,18>;	! *** DEBUG ONLY ***
			! PUT  PUSHJ SREG,UUOSWITCH  INTO #41
			JOB41 ← #260↑27 OR SREG<0,0>↑23 OR UUOSWITCH<0,0>;
		where the routine
			ROUTINE UUOSWITCH= JRST(0,UUOHANDLERS[ .JOB41<27,9> ],0,1);
		for obvious reasons must be in a separate module which is
		compiled without FSAVE, TIMING, or DEBUG switches (/F,/T,/D).


	*The values (octal)
	#400000000000   and   #377777000000
	must be avoided, but this shouldn't be difficult.